\rcube_storage

Abstract class for accessing mail messages storage server

Summary

Methods
Properties
Constants
connect()
close()
is_connected()
check_connection()
get_error_code()
get_error_str()
get_response_code()
set_options()
get_option()
set_debug()
set_charset()
set_folder()
get_folder()
set_page()
get_page()
set_pagesize()
get_pagesize()
set_search_set()
get_search_set()
get_capability()
set_threading()
get_threading()
check_permflag()
get_hierarchy_delimiter()
get_namespace()
count()
list_flags()
list_messages()
index()
search()
search_once()
refresh_search()
get_message()
get_message_headers()
get_message_part()
get_body()
get_raw_body()
get_raw_headers()
print_raw_body()
set_flag()
unset_flag()
save_message()
move_message()
copy_message()
delete_message()
expunge_message()
list_folders_subscribed()
list_folders()
subscribe()
unsubscribe()
create_folder()
rename_folder()
delete_folder()
expunge_folder()
clear_folder()
folder_exists()
folder_size()
folder_namespace()
folder_attributes()
folder_data()
folder_info()
folder_status()
folder_sync()
mod_folder()
folder_validate()
create_default_folders()
is_special_folder()
get_special_folders()
set_special_folders()
get_quota()
set_acl()
delete_acl()
get_acl()
list_rights()
my_rights()
set_metadata()
delete_metadata()
get_metadata()
clear_cache()
get_cache()
cache_gc()
$conn
$folder_types
UNKNOWN
NOPERM
READONLY
TRYCREATE
INUSE
OVERQUOTA
ALREADYEXISTS
NONEXISTENT
CONTACTADMIN
DUAL_USE_FOLDERS
parse_uids()
$folder
$default_charset
$options
$page_size
$list_page
$threading
$search_set
$icache
$all_headers
N/A
No private methods found
No private properties found
N/A

Constants

UNKNOWN

UNKNOWN = 0

NOPERM

NOPERM = 1

READONLY

READONLY = 2

TRYCREATE

TRYCREATE = 3

INUSE

INUSE = 4

OVERQUOTA

OVERQUOTA = 5

ALREADYEXISTS

ALREADYEXISTS = 6

NONEXISTENT

NONEXISTENT = 7

CONTACTADMIN

CONTACTADMIN = 8

DUAL_USE_FOLDERS

DUAL_USE_FOLDERS = 'X-DUAL-USE-FOLDERS'

Properties

$conn

$conn : mixed

Instance of connection object e.g. rcube_imap_generic

Type

mixed

$folder_types

$folder_types : array

List of supported special folder types

Type

array

$folder

$folder

$default_charset

$default_charset

$options

$options

$page_size

$page_size

$list_page

$list_page

$threading

$threading

$search_set

$search_set

$icache

$icache : array

Internal (in-memory) cache

Type

array

$all_headers

$all_headers : array

All (additional) headers used (in any way) by Roundcube Not listed here: DATE, FROM, TO, CC, REPLY-TO, SUBJECT, CONTENT-TYPE, LIST-POST (used for messages listing) are hardcoded in rcube_imap_generic::fetchHeaders()

Type

array

Methods

connect()

connect(string  $host, string  $user, string  $pass, int  $port = 143, string  $use_ssl = null) : bool

Connect to the server

Parameters

string $host

Host to connect

string $user

Username for IMAP account

string $pass

Password for IMAP account

int $port

Port to connect to

string $use_ssl

SSL schema (either ssl or tls) or null if plain connection

Returns

bool —

True on success, False on failure

close()

close() : mixed

Close connection. Usually done on script shutdown

Returns

mixed —

is_connected()

is_connected() : bool

Checks connection state.

Returns

bool —

True on success, False on failure

check_connection()

check_connection() : bool

Check connection state, connect if not connected.

Returns

bool —

Connection state.

get_error_code()

get_error_code() : int

Returns code of last error

Returns

int —

Error code

get_error_str()

get_error_str() : string

Returns message of last error

Returns

string —

Error message

get_response_code()

get_response_code() : int

Returns code of last command response

Returns

int —

Response code (class constant)

set_options()

set_options(array  $opt) : mixed

Set connection and class options

Parameters

array $opt

Options array

Returns

mixed —

get_option()

get_option(string  $name) : mixed

Get connection/class option

Parameters

string $name

Option name

Returns

mixed —

set_debug()

set_debug(bool  $dbg = true) : mixed

Activate/deactivate debug mode.

Parameters

bool $dbg

True if conversation with the server should be logged

Returns

mixed —

set_charset()

set_charset(string  $cs) : mixed

Set default message charset.

This will be used for message decoding if a charset specification is not available

Parameters

string $cs

Charset string

Returns

mixed —

set_folder()

set_folder(string  $folder) : mixed

Set internal folder reference.

All operations will be performed on this folder.

Parameters

string $folder

Folder name

Returns

mixed —

get_folder()

get_folder() : string

Returns the currently used folder name

Returns

string —

Name of the folder

set_page()

set_page(int  $page) : mixed

Set internal list page number.

Parameters

int $page

Page number to list

Returns

mixed —

get_page()

get_page() : int

Gets internal list page number.

Returns

int —

Page number

set_pagesize()

set_pagesize(int  $size) : mixed

Set internal page size

Parameters

int $size

Number of messages to display on one page

Returns

mixed —

get_pagesize()

get_pagesize() : int

Get internal page size

Returns

int —

Number of messages to display on one page

set_search_set()

set_search_set(mixed  $set) : mixed

Save a search result for future message listing methods.

Parameters

mixed $set

Search set in driver specific format

Returns

mixed —

get_search_set()

get_search_set() : array

Return the saved search set.

Returns

array —

Search set in driver specific format, NULL if search wasn't initialized

get_capability()

get_capability(string  $cap) : mixed

Returns the storage server's (IMAP) capability

Parameters

string $cap

Capability name

Returns

mixed —

Capability value or True if supported, False if not

set_threading()

set_threading(bool  $enable = false) : mixed

Sets threading flag to the best supported THREAD algorithm.

Enable/Disable threaded mode.

Parameters

bool $enable

True to enable threading

Returns

mixed —

Threading algorithm or False if THREAD is not supported

get_threading()

get_threading() : mixed

Get current threading flag.

Returns

mixed —

Threading algorithm or False if THREAD is not supported or disabled

check_permflag()

check_permflag(string  $flag) : bool

Checks the PERMANENTFLAGS capability of the current folder and returns true if the given flag is supported by the server.

Parameters

string $flag

Permanentflag name

Returns

bool —

True if this flag is supported

get_hierarchy_delimiter()

get_hierarchy_delimiter() : string

Returns the delimiter that is used by the server for folder hierarchy separation.

Returns

string —

Delimiter string

get_namespace()

get_namespace(string  $name = null) : array

Get namespace

Parameters

string $name

Namespace array index: personal, other, shared, prefix

Returns

array —

Namespace data

count()

count(string  $folder = null, string  $mode = 'ALL', bool  $force = false, bool  $status = true) : int

Get messages count for a specific folder.

Parameters

string $folder

Folder name

string $mode

Mode for count [ALL|THREADS|UNSEEN|RECENT|EXISTS]

bool $force

Force reading from server and update cache

bool $status

Enables storing folder status info (max UID/count), required for folder_status()

Returns

int —

Number of messages

list_flags()

list_flags(string  $folder, array  $uids, int  $mod_seq = null) : array

Public method for listing message flags

Parameters

string $folder

Folder name

array $uids

Message UIDs

int $mod_seq

Optional MODSEQ value

Returns

array —

Indexed array with message flags

list_messages()

list_messages(string  $folder = null, int  $page = null, string  $sort_field = null, string  $sort_order = null, int  $slice) : array

Public method for listing headers.

Parameters

string $folder

Folder name

int $page

Current page to list

string $sort_field

Header field to sort by

string $sort_order

Sort order [ASC|DESC]

int $slice

Number of slice items to extract from result array

Returns

array —

Indexed array with message header objects

index()

index(string  $folder = null, string  $sort_field = null, string  $sort_order = null) : \rcube_result_index|\rcube_result_thread

Return sorted list of message UIDs

Parameters

string $folder

Folder to get index from

string $sort_field

Sort column

string $sort_order

Sort order [ASC, DESC]

Returns

\rcube_result_index|\rcube_result_thread —

List of messages (UIDs)

search()

search(string  $folder = null, string  $str = 'ALL', string  $charset = null, string  $sort_field = null) : mixed

Invoke search request to the server.

Parameters

string $folder

Folder name to search in

string $str

Search criteria

string $charset

Search charset

string $sort_field

Header field to sort by

Returns

mixed —

search_once()

search_once(string  $folder = null, string  $str = 'ALL') : \rcube_result_index

Direct (real and simple) search request (without result sorting and caching).

Parameters

string $folder

Folder name to search in

string $str

Search string

Returns

\rcube_result_index —

Search result (UIDs)

refresh_search()

refresh_search() : array

Refresh saved search set

Returns

array —

Current search set

get_message()

get_message(int  $uid, string  $folder = null) : object

Fetch message headers and body structure from the server and build an object structure.

Parameters

int $uid

Message UID to fetch

string $folder

Folder to read from

Returns

object —

rcube_message_header Message data

get_message_headers()

get_message_headers(mixed  $uid, string  $folder = null, bool  $force = false) : \rcube_message_header

Return message headers object of a specific message

Parameters

mixed $uid
string $folder

Folder to read from

bool $force

True to skip cache

Returns

\rcube_message_header —

Message headers

get_message_part()

get_message_part(int  $uid, string  $part = 1, \rcube_message_part  $o_part = null, mixed  $print = null, resource  $fp = null, bool  $skip_charset_conv = false) : string

Fetch message body of a specific message from the server

Parameters

int $uid

Message UID

string $part

Part number

\rcube_message_part $o_part

Part object created by get_structure()

mixed $print

True to print part, resource to write part contents in

resource $fp

File pointer to save the message part

bool $skip_charset_conv

Disables charset conversion

Returns

string —

Message/part body if not printed

get_body()

get_body(int  $uid, mixed  $part = 1) : string

Fetch message body of a specific message from the server

Parameters

int $uid

Message UID

mixed $part

Returns

string —

$part Message/part body

get_raw_body()

get_raw_body(int  $uid, resource  $fp = null, string  $part = null) : string

Returns the whole message source as string (or saves to a file)

Parameters

int $uid

Message UID

resource $fp

File pointer to save the message

string $part

Optional message part ID

Returns

string —

Message source string

get_raw_headers()

get_raw_headers(int  $uid, string  $part = null) : string

Returns the message headers as string

Parameters

int $uid

Message UID

string $part

Optional message part ID

Returns

string —

Message headers string

print_raw_body()

print_raw_body(int  $uid, bool  $formatted = true) : mixed

Sends the whole message source to stdout

Parameters

int $uid

Message UID

bool $formatted

Enables line-ending formatting

Returns

mixed —

set_flag()

set_flag(mixed  $uids, string  $flag, string  $folder = null, bool  $skip_cache = false) : bool

Set message flag to one or several messages

Parameters

mixed $uids

Message UIDs as array or comma-separated string, or '*'

string $flag

Flag to set: SEEN, UNDELETED, DELETED, RECENT, ANSWERED, DRAFT, MDNSENT

string $folder

Folder name

bool $skip_cache

True to skip message cache clean up

Returns

bool —

Operation status

unset_flag()

unset_flag(mixed  $uids, string  $flag, string  $folder = null) : bool

Remove message flag for one or several messages

Parameters

mixed $uids

Message UIDs as array or comma-separated string, or '*'

string $flag

Flag to unset: SEEN, DELETED, RECENT, ANSWERED, DRAFT, MDNSENT

string $folder

Folder name

Returns

bool —

Operation status

save_message()

save_message(string  $folder, string|array  $message, string  $headers = '', bool  $is_file = false, array  $flags = [], mixed  $date = null) : int|bool

Append a mail message (source) to a specific folder.

Parameters

string $folder

Target folder

string|array $message

The message source string or filename or array (of strings and file pointers)

string $headers

Headers string if $message contains only the body

bool $is_file

True if $message is a filename

array $flags

Message flags

mixed $date

Message internal date

Returns

int|bool —

Appended message UID or True on success, False on error

move_message()

move_message(mixed  $uids, string  $to, string  $from = null) : bool

Move message(s) from one folder to another.

Parameters

mixed $uids

Message UIDs as array or comma-separated string, or '*'

string $to

Target folder

string $from

Source folder

Returns

bool —

True on success, False on error

copy_message()

copy_message(mixed  $uids, string  $to, string  $from = null) : bool

Copy message(s) from one mailbox to another.

Parameters

mixed $uids

Message UIDs as array or comma-separated string, or '*'

string $to

Target folder

string $from

Source folder

Returns

bool —

True on success, False on error

delete_message()

delete_message(mixed  $uids, string  $folder = null) : bool

Mark message(s) as deleted and expunge.

Parameters

mixed $uids

Message UIDs as array or comma-separated string, or '*'

string $folder

Source folder

Returns

bool —

True on success, False on error

expunge_message()

expunge_message(mixed  $uids, string  $folder = null, bool  $clear_cache = true) : bool

Expunge message(s) and clear the cache.

Parameters

mixed $uids

Message UIDs as array or comma-separated string, or '*'

string $folder

Folder name

bool $clear_cache

False if cache should not be cleared

Returns

bool —

True on success, False on error

list_folders_subscribed()

list_folders_subscribed(string  $root = '', string  $name = '*', string  $filter = null, string  $rights = null, bool  $skip_sort = false) : array

Get a list of subscribed folders.

Parameters

string $root

Optional root folder

string $name

Optional name pattern

string $filter

Optional filter

string $rights

Optional ACL requirements

bool $skip_sort

Enable to return unsorted list (for better performance)

Returns

array —

List of folders

list_folders()

list_folders(string  $root = '', string  $name = '*', mixed  $filter = null, string  $rights = null, bool  $skip_sort = false) : array

Get a list of all folders available on the server.

Parameters

string $root

IMAP root dir

string $name

Optional name pattern

mixed $filter

Optional filter

string $rights

Optional ACL requirements

bool $skip_sort

Enable to return unsorted list (for better performance)

Returns

array —

Indexed array with folder names

subscribe()

subscribe(array  $folders) : bool

Subscribe to a specific folder(s)

Parameters

array $folders

Folder name(s)

Returns

bool —

True on success

unsubscribe()

unsubscribe(array  $folders) : bool

Unsubscribe folder(s)

Parameters

array $folders

Folder name(s)

Returns

bool —

True on success

create_folder()

create_folder(string  $folder, bool  $subscribe = false, string  $type = null, bool  $noselect = false) : bool

Create a new folder on the server.

Parameters

string $folder

New folder name

bool $subscribe

True if the new folder should be subscribed

string $type

Optional folder type (junk, trash, drafts, sent, archive)

bool $noselect

Make the folder \NoSelect folder by adding hierarchy separator at the end (useful for server that do not support both folders and messages as folder children)

Returns

bool —

True on success, False on error

rename_folder()

rename_folder(string  $folder, string  $new_name) : bool

Set a new name to an existing folder

Parameters

string $folder

Folder to rename

string $new_name

New folder name

Returns

bool —

True on success, False on error

delete_folder()

delete_folder(string  $folder) : bool

Remove a folder from the server.

Parameters

string $folder

Folder name

Returns

bool —

True on success, False on error

expunge_folder()

expunge_folder(string  $folder = null, bool  $clear_cache = true) : bool

Send expunge command and clear the cache.

Parameters

string $folder

Folder name

bool $clear_cache

False if cache should not be cleared

Returns

bool —

True on success, False on error

clear_folder()

clear_folder(string  $folder = null) : bool

Remove all messages in a folder.

.

Parameters

string $folder

Folder name

Returns

bool —

True on success, False on error

folder_exists()

folder_exists(string  $folder, bool  $subscription = false) : bool

Checks if folder exists and is subscribed

Parameters

string $folder

Folder name

bool $subscription

Enable subscription checking

Returns

bool —

True if folder exists, False otherwise

folder_size()

folder_size(string  $folder) : int

Get folder size (size of all messages in a folder)

Parameters

string $folder

Folder name

Returns

int —

Folder size in bytes, False on error

folder_namespace()

folder_namespace(string  $folder) : string

Returns the namespace where the folder is in

Parameters

string $folder

Folder name

Returns

string —

One of 'personal', 'other' or 'shared'

folder_attributes()

folder_attributes(string  $folder, bool  $force = false) : array

Gets folder attributes (from LIST response, e.g. \Noselect, \Noinferiors).

Parameters

string $folder

Folder name

bool $force

Set to True if attributes should be refreshed

Returns

array —

Options list

folder_data()

folder_data(string  $folder) : array

Gets connection (and current folder) data: UIDVALIDITY, EXISTS, RECENT, PERMANENTFLAGS, UIDNEXT, UNSEEN

Parameters

string $folder

Folder name

Returns

array —

Data

folder_info()

folder_info(string  $folder) : array

Returns extended information about the folder.

Parameters

string $folder

Folder name

Returns

array —

Data

folder_status()

folder_status(string  $folder = null, array  $diff = []) : int

Returns current status of a folder (compared to the last time use)

Parameters

string $folder

Folder name

array $diff

Difference data

Returns

int —

Folder status

folder_sync()

folder_sync(string  $folder) : mixed

Synchronizes messages cache.

Parameters

string $folder

Folder name

Returns

mixed —

mod_folder()

mod_folder(string  $folder, string  $mode = 'out') : string

Modify folder name according to namespace.

For output it removes prefix of the personal namespace if it's possible. For input it adds the prefix. Use it before creating a folder in root of the folders tree.

Parameters

string $folder

Folder name

string $mode

Mode name (out/in)

Returns

string —

Folder name

folder_validate()

folder_validate(string  $folder, string  $char = null) : bool

Check if the folder name is valid

Parameters

string $folder

Folder name (UTF-8)

string $char

First forbidden character found

Returns

bool —

True if the name is valid, False otherwise

create_default_folders()

create_default_folders() : mixed

Create all folders specified as default

Returns

mixed —

is_special_folder()

is_special_folder(mixed  $name) : mixed

Check if specified folder is a special folder

Parameters

mixed $name

Returns

mixed —

get_special_folders()

get_special_folders(mixed  $forced = false) : mixed

Return configured special folders

Parameters

mixed $forced

Returns

mixed —

set_special_folders()

set_special_folders(mixed  $specials) : mixed

Set special folder associations stored in backend

Parameters

mixed $specials

Returns

mixed —

get_quota()

get_quota(string  $folder = null) : mixed

Get mailbox quota information.

Parameters

string $folder

Folder name

Returns

mixed —

Quota info or False if not supported

set_acl()

set_acl(string  $folder, string  $user, string  $acl) : bool

Changes the ACL on the specified folder (SETACL)

Parameters

string $folder

Folder name

string $user

User name

string $acl

ACL string

Returns

bool —

True on success, False on failure

delete_acl()

delete_acl(string  $folder, string  $user) : bool

Removes any <identifier,rights> pair for the specified user from the ACL for the specified folder (DELETEACL).

Parameters

string $folder

Folder name

string $user

User name

Returns

bool —

True on success, False on failure

get_acl()

get_acl(string  $folder) : array

Returns the access control list for a folder (GETACL).

Parameters

string $folder

Folder name

Returns

array —

User-rights array on success, NULL on error

list_rights()

list_rights(string  $folder, string  $user) : array

Returns information about what rights can be granted to the user (identifier) in the ACL for the folder (LISTRIGHTS).

Parameters

string $folder

Folder name

string $user

User name

Returns

array —

List of user rights

my_rights()

my_rights(string  $folder) : array

Returns the set of rights that the current user has to a folder (MYRIGHTS).

Parameters

string $folder

Folder name

Returns

array —

MYRIGHTS response on success, NULL on error

set_metadata()

set_metadata(string  $folder, array  $entries) : bool

Sets metadata/annotations (SETMETADATA/SETANNOTATION)

Parameters

string $folder

Folder name (empty for server metadata)

array $entries

Entry-value array (use NULL value as NIL)

Returns

bool —

True on success, False on failure

delete_metadata()

delete_metadata(string  $folder, array  $entries) : bool

Unsets metadata/annotations (SETMETADATA/SETANNOTATION)

Parameters

string $folder

Folder name (empty for server metadata)

array $entries

Entry names array

Returns

bool —

True on success, False on failure

get_metadata()

get_metadata(string  $folder, array  $entries, array  $options = [], bool  $force = false) : array

Returns folder metadata/annotations (GETMETADATA/GETANNOTATION).

Parameters

string $folder

Folder name (empty for server metadata)

array $entries

Entries

array $options

Command options (with MAXSIZE and DEPTH keys)

bool $force

Disables cache use

Returns

array —

Metadata entry-value hash array on success, NULL on error

clear_cache()

clear_cache(string  $key = null, bool  $prefix_mode = false) : mixed

Clears the cache.

Parameters

string $key

Cache key name or pattern

bool $prefix_mode

Enable it to clear all keys starting with prefix specified in $key

Returns

mixed —

get_cache()

get_cache(string  $key) : mixed

Returns cached value

Parameters

string $key

Cache key

Returns

mixed —

Cached value

cache_gc()

cache_gc() : mixed

Delete outdated cache entries

Returns

mixed —

parse_uids()

parse_uids(mixed  $uids) : array

Parse message UIDs input

Parameters

mixed $uids

UIDs array or comma-separated list or '' or '1:'

Returns

array —

Two elements array with UIDs converted to list and ALL flag